# Device Note - Potentiometer Module

## What It Is
A rotary potentiometer module is a variable resistor on a small breakout board. Turning the knob changes the resistance between its wiper and one end terminal, which changes the voltage on the output pin from near-zero to near-supply.

## Why It Is Used
Potentiometers give a smooth analogue input — a continuous range of values rather than just on or off. They let students explore how a physical action (turning a knob) maps to a number inside the microcontroller.

## Pin Overview
This module uses a 3-pin header:
- `VCC` — supply voltage (3.3 V or 5 V)
- `GND` — ground
- `OUT` — analogue output (wiper voltage, varies with knob position)

Connection in this course:
- `OUT` -> `PA6` (ADC1 channel 6 on the Bluepill)

## Control Behavior
- The output voltage tracks knob position from ~0 V (fully anticlockwise) to ~VCC (fully clockwise).
- The STM32 ADC converts this to a 12-bit number: 0–4095 counts (`pot_raw`).
- The firmware also reports a percentage: 0–100% (`pot_percent`).
- Command `GET_POT` returns both values.
- Both values stream automatically in the compact USB telemetry frame every 120 ms.

## Wiring Rules
- Use 3.3 V for VCC so the ADC input stays within the STM32's safe analogue input range (0 V to VDDA = 3.3 V).
- Keep the signal wire away from motor supply wires if a motor driver is also connected.
- No pull-up or pull-down resistor is needed — the wiper drives the ADC pin directly.

## Common Failure Modes
- Wrong VCC (5 V instead of 3.3 V) — `pot_raw` pegs at 4095, may stress the ADC input.
- Wiper pin swapped with VCC or GND — reads fixed 0 or fixed 4095.
- Loose connection on `OUT` — ADC floats and gives unstable readings.
- Knob at an extreme mechanical stop — normal; `pot_raw` will be 0 or near 4095.

## Classroom Notes
- Let students turn the knob while watching `pot_raw` change live in the watch strip — the immediate feedback makes ADC values feel real.
- Ask students to predict what value they expect before turning, then check.
- Relate `pot_percent` to real-world controls: speaker volume, heating thermostat, light dimmer.
- A good early automation exercise: use `pot_percent` as a condition threshold — e.g. "if pot is above 50%, turn green LED on".

## Integration With This Course
- Pairs well with Lesson 3 (Commands, Modes & State) when introducing analogue input alongside digital GPIO.
- Pairs well with Lesson 10 (Automation Tool & Control Logic) — use `{pot_percent}` as a live variable in automation conditions and text expressions.
- Telemetry keys: `pot_raw` (0–4095), `pot_percent` (0–100%)
- Automation variable tokens: `{pot_raw}`, `{pot_percent}`